\chapter{Lists}
\index{list|(}

This chapter assumes knowledge of the scalar, matrix and string
variable types.  A list is a convenient way to group together
different types of variables, and treat them as one variable.
This is very similar to the way a Pascal record, or C structure is
made up.

A nice thing about lists is that they only contain objects that are
explicitly installed, regardless of the index values.  For instance, a
list with index values of \verb+1+ and \verb+100+ will only contains
two items, the elements for the \verb+1+ and \verb+100+ indices, no
more. Furthermore, lists can be more efficient than appending rows or
columns onto matrices, since the memory management overhead is less.

Lists can also be a convenient way to have an array that indexes from
zero. This may not be as efficient as using a matrix, though if the
problem is expressed more clearly, then a list may be appropriate.

\section{List Creation}
\index{list!creation|(} 
A list can be created either explicitly or implicitly.  Generally, you
will use the implicit method, but we will look at both methods. Also,
note that the two methods are not mutually exclusive.  In particular,
note that it is quite legitimate to create a list explicitly, then add
more elements implicitly.

\subsection{Explicit Creation}

Creating a list explicitly is common is user defined functions
(covered in the next chapter), where you calculate the various
results, then make a list that containing them.

The explicit list creation operators are \verb+<<+ and \verb+>>+.  The
most basic operation is to create an empty list. Here is an example of
creating a list (called \verb+mylist+), with no elements:
\begin{verbatim}
>  mylist = << >>
        <<>>
\end{verbatim}

More useful is creating a list with some elements already in it. You
use the same operators, with the names of the variables you want to
put into the list within the the list operators.  A semicolon should
be used to seperate the variables.  Here is an example:
\begin{verbatim}
> a = "a string"
a string
> b = 23.5
 b =
     23.5
> c = rand(2,2)
 c =
        1      0.647  
    0.975      0.333  
> heterogenous = << a ; b ; c >>
   1            2            3     
\end{verbatim}

Notice how the variables are indexed using scalars.  Indexing will be
discussed later, but suffice for now to say that the index is how you
get the induvidual elements back out of the list.  The index is often
more useful if you use strings that add some meaning to the values
contained within the list.  You do this by assigning the values to a
string label, as shown here:

\begin{verbatim}
> a = "a string"                
a string
> b = 23.5                      
 b =
     23.5
> heterogenous2 = << String=a ; Weight=b ; Product=rand(3,3) >>
   Product      String       Weight
\end{verbatim}

The labels within a list are only visible in relation to that list.
That is, they don't appear in the global symbol table.  Also, note
that the values that are being copied into the list do not
neccessarily have to exist before the list is created.  The example
above shows that you can create the contents at the same time this
list is created.   

\subsection{Implicit Creation}

Implicit creation is most commonly used at the command line, as it is
easier and takes less forward planning.  The basic idea is that you
can just add an element to a list without regard to whether that list
actually exists.   If the list doesn't exist, it will be created, and
then the element will be added.

Let's look at an example:
\begin{verbatim}
> who()
eps  pi                  
> mylist.vect = 1:5
   vect         
> mylist.m = rand(2,3)
   m            vect         
> mylist.stringval = "one point four two"
   m            stringval    vect  
\end{verbatim}

In the explicit method, we saw how it was possible to assign elements
without indicies, and have \RLaB\ supply scalar indicies
automatically. There isn't any way to do this with the implicit list
creation method, however it is possible to get scalar indicies if you
want them.  To do so, you have to use square braces, \verb+[+ and
\verb+]+, around the scalar index. Carrying on from the previous
example, if you want another element with the scalar index \verb+5+,
you would do the following.

\begin{verbatim}
> mylist.[5] = 4:6:0.5
   5            m            stringval    vect
\end{verbatim}

However the braces are good for much more than simple scalar
assignment.  Those braces are actually forcing evaluation of their
contents, and then convert the result to a string. Now evaluation of a
scalar constant is pretty simple, but here are more complex examples,
again following on from previous examples:
\begin{verbatim}
> e=5 
 e =
        5
> mylist.[e+sqrt(4)] = 4.56
   5            7            m            stringval    vect
> stringmat = [ "string1"; "string2" ; "string3" ] 
 stringmat =
string1  
string2  
string3  
> mylist.[stringmat[2]] = " more characters"      
   5            7            m            string2      stringval    
   vect         
\end{verbatim}

Although there is considerable power in using scalar indicies, it is
strongly recommended that you use descriptive strings unless you are
planning on using that power.
\index{list!creation|)}

\section{List Indexing}
\index{list!indexing|(}
To reference a list member, two methods are available.  Both are a lot
like the implicit list creation, just without the equals sign and
right hand side. 

The first method is of the form {\it listname\verb+.+index} .  It
interprets {\it index} as a character string, and uses that string as
an index to the list specifies by {\it listname}.

The second method uses the square braces, \verb+[+ and \verb+]+, and
forces evaluation of the contents of the braces as a string, and then
uses the resulting string as an index to the list.  The expression
inside the braces must evaluate to a scalar or string.  This method is
required if you used the explicit creation method, and did not assign
indicies.

\begin{verbatim}
> // some equivalent methods of getting the first element
> mylist.[5]                                
 5 =
        4        4.5          5        5.5          6  
> e=5                                             
 e =
        5
> mylist.[e]
 5 =
        4        4.5          5        5.5          6  
> mylist.[2+sqrt(9)]
 5 =
        4        4.5          5        5.5          6 
> // some more equivalents
> mylist.stringval
one point four two
> mylist.["stringval"]
one point four two
> mylist.["stri" + "ngval"]
one point four two
\end{verbatim}


\subsection{Functions returning lists}

We have already alluded to the fact that some functions return lists.
This is most common when the return value is made up of different
types, or is made up of matrices with different dimensions.  An
example is the \verb+eig+ function, which returns a list containing
two matricies, as shown here:
\begin{verbatim}
> a= rand(4,4)
 a =
    0.665      0.655      0.299     0.0918  
   0.0847      0.129      0.265      0.902  
    0.204       0.91        0.7       0.96  
    0.167      0.112       0.95      0.915  
> a_eig = eig(a)
   val          vec          
> show(a_eig.val)
   name:      val      
   class:     num      
   type:      complex  
     nr:      1        
     nc:      4        
> show(a_eig.vec)
   name:      vec      
   class:     num      
   type:      complex  
     nr:      4        
     nc:      4        
\end{verbatim}

However sometimes you don't want all the information.  For instance,
we might want to conduct a test on the eigenvalues.  So we can throw
away the eigenvectors, and just look at the eigenvalues.  We can do
this using either method, as shown here:
\begin{verbatim}
> eigenvalues1 = eig(a).val   
 eigenvalues1 =
 matrix columns 1 thru 3
              0.554 + 0i               2.15 + 0i         -0.148 + 0.457i

 matrix columns 4 thru 4
         -0.148 - 0.457i
> eigenvalues2 = eig(a).["val"]
 eigenvalues2 =
 matrix columns 1 thru 3
              0.554 + 0i               2.15 + 0i         -0.148 + 0.457i

 matrix columns 4 thru 4
         -0.148 - 0.457i
\end{verbatim}

This can be applied to any function that evaluates to a list type.
\index{list!indexing|)}

\section{Global Symbol Table}
\index{global symbol table}

The \RLaB\ symbol table is just a list. It can be referenced with the
special symbol \verb+$$+ . The symbol-table can be used like other lists,
with certain exceptions.
\begin{itemize}
  \item  The global symbol table cannot be copied.
  \item  The global symbol table cannot be destroyed.
\end{itemize}


Why would you want to use \verb+$$+ ? Well, you might use it to reference a
variable with a string. For example:

\begin{verbatim}
> printf ("Enter variable name to display: "); a= getline("stdin");
Enter variable name to display: eps
> $$.[a.[1]]
 eps =
 1.11e-16
\end{verbatim}

Another use might be to list the contents of the variables that are
defined.
\begin{verbatim}
>  for (i in members($$))              
    {                                   
      if (class ($$.[i]) != "function") 
      {                                 
        $$.[i] ?                        
      }                                 
    }         
 eigenvalues1 =
 matrix columns 1 thru 3
              0.554 + 0i               2.15 + 0i         -0.148 + 0.457i

 matrix columns 4 thru 4
         -0.148 - 0.457i
 eigenvalues2 =
 matrix columns 1 thru 3
              0.554 + 0i               2.15 + 0i         -0.148 + 0.457i

 matrix columns 4 thru 4
         -0.148 - 0.457i
 eps =
 1.11e-16
 pi =
     3.14
\end{verbatim}


\index{list|)}




